Updating Kivy from a previous release
When updating from a previous Kivy release, all the Kivy dependencies must be updated first. Typically, just adding –upgrade to the pip install … commands below is sufficient for pip to update them.
Warning
When updating from Kivy 1.10.1 or lower to 1.11.0 or higher, one must manually uninstall all kivy dependencies before upgrading because won’t update them properly. This is done with:
python -m pip uninstall -y kivy.deps.glew kivy.deps.gstreamer kivy.deps.sdl2 kivy.deps.angle
assuming all the dependencies were previously installed. See Kivy’s dependencies for more details.
After uninstalling, continue with the installation below.
Installing the kivy stable release
Warning
Kivy 1.11.1 is the last release that supports Python 2.
Now that python is installed, open the Command line and make sure
python is available by typing python --version
. Then, do the following to
create a new virtual environment
(optionally) and install the most recent stable
kivy release (1.11.1) and its dependencies.
Ensure you have the latest pip, wheel, and virtualenv:
python -m pip install --upgrade pip wheel setuptools virtualenv
Optionally create a new virtual environment for your Kivy project. Highly recommended:
First create the environment named kivy_venv in your current directory:
python -m virtualenv kivy_venv
Activate the virtual environment. You’ll have to do this step from the current directory every time you start a new terminal. On windows CMD do:
kivy_venv\Scripts\activate
If you’re in a bash terminal, instead do:
source kivy_venv/Scripts/activate
Your terminal should now preface the path with something like (kivy_venv), indicating that the kivy_venv environment is active. If it doesn’t say that, the virtual environment is not active.
Install the dependencies (skip gstreamer (~120MB) if not needed, see Kivy’s dependencies). If you are upgrading Kivy, see Updating Kivy from a previous release:
python -m pip install docutils pygments pypiwin32 kivy_deps.sdl2==0.1.* kivy_deps.glew==0.1.* python -m pip install kivy_deps.gstreamer==0.1.*
Note
If you encounter a MemoryError while installing, add after pip install the –no-cache-dir option.
For Python 3.5+, you can also use the angle backend instead of glew. This can be installed with:
python -m pip install kivy_deps.angle==0.1.*
Warning
When installing, pin kivy’s dependencies to the specific version that was released on pypi when your kivy version was released, like above. Otherwise you may get an incompatible dependency when it is updated in the future.
Install kivy:
python -m pip install kivy==1.11.1
(Optionally) Install the kivy examples:
python -m pip install kivy_examples==1.11.1
The examples are installed in the share directory under the root directory where python is installed.
That’s it. You should now be able to import kivy
in python or run a basic
example if you installed the kivy examples:
python kivy_venv\share\kivy-examples\demo\showcase\main.py
Replace kivy_venv with the path where python is installed if you didn’t use a virtualenv.
Note
If you encounter any permission denied errors, try opening the Command prompt as administrator and trying again. The best solution for this is to use a virtual environment instead.
What are wheels, pip and wheel
In Python, packages such as Kivy can be installed with the python package
manager, pip. Some packages such as Kivy
require additional steps, such as compilation, when installing using the Kivy
source code with pip. Wheels (with a .whl
extension) are pre-built
distributions of a package that has already been compiled and do not require
additional steps to install.
When hosted on pypi one installs a wheel
using pip
, e.g. python -m pip install kivy
. When downloading and
installing a wheel directly, python -m pip install wheel_file_name
is used,
such as:
python -m pip install C:\Kivy-1.9.1.dev-cp27-none-win_amd64.whl
Kivy’s dependencies
We offer wheels for Kivy and its dependencies separately so only desired
dependencies need be installed. The dependencies are offered as
optional sub-packages of kivy_deps, e.g. kivy_deps.sdl2
.
Note
In Kivy 1.11.0 we transitioned the kivy Windows dependencies from the kivy.deps.xxx namespace stored under kivy/deps/xxx to the kivy_deps.xxx namespace stored under kivy_deps/xxx. Pip is sometimes not able to distinguish between these two formats, so follow the instructions at Updating Kivy from a previous release when upgrading from a older Kivy. See here for more details.
Currently on Windows, we provide the following dependency wheels:
- gstreamer for audio and video
- glew and/or angle (3.5 only) for OpenGL
- sdl2 for control and/or OpenGL.
One can select which of these to use for OpenGL using the KIVY_GL_BACKEND envrionment variable by setting it to glew (the default), angle, or sdl2. angle is currently in an experimental phase as a substitute for glew on Python 3.5+ only.
gstreamer is an optional dependency which only needs to be installed if video display or audio is desired. ffpyplayer is an alternate dependency for audio or video.